\chapter{Užívateľská dokumentácia}
\label{app:user_documentation}

\section{Požiadavky a spustenie programu}

Program je prispôsobený na spúšťanie a testovanie na \uv{Linux-based} operačnom systéme. Podmienkou je mať nainštalovaný Qt framework (odporúčaná verzia je 4.7.4 alebo vyššia) a kompilátor pre C++.

Bližšie informácie inštulácii Qt framework sa nachádzajú na oficiálnych internetových stránkach~\cite{qt}. Na linuxových operačných systémoch sa dá Qt framework nainštalovať jednoducho pomocou príkazu \textit{apt-get install}.

Minimálna konfigurácia hardware predstavuje aspoň 4GB RAM, 1GHz CPU.
 
K dispozícii je aj projekt pre Visual Studio 2012, avšak pre testovanie vo veľkom nie je prispôsobený.

Skripty na účel testovania, spolu so zdrojovým kódom pre Linux i Windows (projekt pre Visual Studio 2012) sú dostupné v repozitári na nasledovnej URL adrese: \url{http://code.google.com/p/prossigen/}\footnote{Pre priame stiahnutie SVN repozitára treba použiť príkaz \uv{svn checkout http://prossigen.googlecode.com/svn/trunk2012/ prossigen-read-only}}.

Na priloženom CD v adresári \textit{spustitelny\_program\_pre\_windows} môžeme nájsť skompilovanú a spustiteľnú verziu programu, ktorý sa dá spustiť cez príkazový riadok. Tento spustiteľný \textit{ProSSiGen.exe} súbor bol testovaný na OS Windows 8 64bit s nainštalovaným Qt framework, nainštalovaným Visual Studiom o verzii 2010 a 2012.

V prípade, že sa nám nepodarí spustiteľný súbor spustiť, je možno potrebné nainštalovať Qt framework a skompilovať projekt pre Visual Studio, ktorý nájdeme v adresári \textit{projekt\_pre\_visual\_studio}. V prípade neúspešnej kompilácie, je potrebné skontrolovať príslušné hlavičkové súbory a cesty ku Qt knižniciam a to nasledovne pre \textit{Debug} mód pre jednotlivé položky takto:
\\
\textit{Project -- Properties -- C/C++ -- General -- Additional Include Directories: 
\\
$<$include adresár projektu ProSSiGen$>$; \\
$<$cesta, kde je nainštalované Qt$>\backslash$include; \\
$<$cesta, kde je nainštalované Qt$>\backslash$include$\backslash$QtCore}
\\
\\
\textit{Project -- Properties -- Linker -- General -- Additional Library Directories: 
\\
$<$include adresár projektu ProSSiGen$>$; \\
$<$cesta, kde je nainštalované Qt$>\backslash$lib}
\\
\\
\textit{Project -- Properties -- Linker -- Input -- Additional Dependencies: 
\\
qtmain.lib;QtCore4.lib;$<$zvyšné knižnice pôvodne zahrnuté$>$}
\\
\\
V prípade \textit{Release} módu sa nastavenia projektu mierne líšia:
\\
\textit{Project -- Properties -- VC++ Directories -- Include Directories: 
\\
$<$cesta, kde je nainštalované Qt$>\backslash$include; \\
$<$cesta, kde je nainštalované Qt$>\backslash$include$\backslash$QtCore;\\
$<$zvyšné položky pôvodne zahrnuté$>$}
\\
\\
\textit{Project -- Properties -- C/C++ -- General -- Additional Include Directories: 
\\
$<$include adresár projektu ProSSiGen$>$; \\
$<$cesta, kde je nainštalované Qt$>\backslash$include; \\
$<$cesta, kde je nainštalované Qt$>\backslash$include$\backslash$QtCore}
\\
\\
\textit{Project -- Properties -- Linker -- General -- Additional Library Directories: 
\\
$<$cesta, kde je nainštalované Qt$>\backslash$lib;\\
$<$zvyšné položky pôvodne zahrnuté$>$}
\\
\\
\textit{Project -- Properties -- Linker -- Input -- Additional Dependencies: 
\\
qtmain.lib;QtCore4.lib;$<$zvyšné knižnice pôvodne zahrnuté$>$}
\\

Projekt sa nechá následne skompilovať a výsledný spustiteľný súbor sa následne spúšťa z príkazového riadku vo formáte:\\ \textit{$>$ ProSSiGen.exe\quad$<$ID prvej štruktúry$> \quad<$ID druhej štruktúry$>\quad<$cesta k adresáru uložených štruktúr$>$\footnote{Dôležité je, aby súbory popisujúce jednotlivé proteíny mali koncovku súboru \textit{.ent}, viď priložený archív s databázou proteínových súborov určené pre testovanie.}}

Pre spustenie na Linuxe sú potrebné zdrojové kódy preň určené, ktoré skompilujeme v adresári projektu \textit{src} nasledovnými príkazmi:\\
\textit{$\$$ qmake}\\
\textit{$\$$ make clean}\\
\textit{$\$$ make}

Vygeneruje sa nám spustiteľný súbor \textit{prossigen}, ktorý spustíme v termináli podobne ako cez príkazový riadok. Uveďme si príklad: \\ \textit{./prossigen ``1nh8a'' ``1h3d\_'' pdb\_database/}



Pri spustiteľnom súbore sa musí taktiež nachádzať konfiguračný súbor \textit{configuration.xml} so zobrazeným ukážkovým obsahom nižšie.\\

\definecolor{gray}{rgb}{0.4,0.4,0.4}
\definecolor{darkblue}{rgb}{0.0,0.0,0.6}
\definecolor{cyan}{rgb}{0.0,0.6,0.6}

\lstloadlanguages{XML}


\lstdefinestyle{listXML}{language=XML, extendedchars=true,  belowcaptionskip=5pt, xleftmargin=1.8em, xrightmargin=0.5em, numbers=left, numberstyle=\small\ttfamily\bf, frame=single, breaklines=true, breakatwhitespace=true, breakindent=0pt, emph={}, emphstyle=\color{red}, basicstyle=\small\ttfamily, columns=fullflexible, showstringspaces=false, commentstyle=\color{gray}\upshape,
morestring=[b]",
morecomment=[s]{<?}{?>},
morecomment=[s][\color{orange}]{<!--}{-->},
keywordstyle=\color{cyan},
stringstyle=\color{black},
tagstyle=\color{darkblue},
morekeywords={xmlns,version,type}
}

\begin{lstlisting}[style=listXML]
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<prossigen_settings>
  <asphere>
    <radius>9</radius>
  </asphere>
  <needleman_wunsh_settings>
    <!-- if another matrix is used, the default scoring 
	  will be applied, i.e. 1 for match, 0 for penalty -->
    <scoring_matrix>BLOSUM62</scoring_matrix>
    <gap_penalty>-4</gap_penalty>
  </needleman_wunsh_settings>
  <gp>
    <termination_criterion_setting>
      <individual_score>1</individual_score>
      <number_of_generations>2000</number_of_generations>
    </termination_criterion_setting>
    <number_of_threads>1</number_of_threads>
    <prob_of_crossover>0.9</prob_of_crossover>
    <prob_of_reproduction>0.1</prob_of_reproduction>
    <!-- The value must be in range of (1;2] -->
    <selective_pressure_parameter>1.8</selective_pressure_parameter>
  </gp>
</prossigen_settings>
\end{lstlisting}

\section{Testovacia časť}

Testovanie pre veľké množstvo štruktúr je prispôsobené pre linuxový operačný systém. Spolu s priloženým zdrojovým kódom na CD sa nachádzajú aj potrebné skripty pre tento účel a sú to:\\
\textit{execute\_tests.sh, get\_next\_diff\_id\_generic.sh, run\_test\_generic.sh, time\_checker\_generic.sh}

Ako hlavný skript pre spustenie je prvý vymenovaný a spúšťa sa so štyrmi parametrami:\\
\textit{./execute\_tests.sh $<$súbor1$>$  $<$súbor2$>$  $<$cesta\_k\_priečinku$>$ $<$počet\_inštancií$>$}

\textit{Súbor1} je súbor, kde na každom riadku sa nachádza ID neklasifikovanej bielkoviny s ID reťazca, \textit{súbor2} je súbor s identifikátormi štruktúr klasifikovaných bielkovín, \textit{cesta\_k\_priečinku} je cesta k priečinku, kde sa nachádzajú súbory s koncovkou \textit{.ent} popisujúce jednotlivé bielkoviny a \textit{počet\_inštancií} je prirodzené číslo predstavujúce počet inštancií programu, ktoré sa spustia paralelne. Pri použití jedného vlákna pre inštanciu a počet inštancií sa odporúča počet troj násobku dostupných procesorových vlákien.

Na CD sa tiež nachádzajú priložené súbory s identifikátormi štruktúr s	 názvom \textit{ids\_complete\_diff\_unique.txt} a \textit{ids\_complete\_orig\_unique.txt}.

Pre testovanie sa odporúča použiť menšia sada neklasifikovaných štruktúr a testovať ich po častiach. Skript totiž zo súboru \textit{súbor1} postupne vyberá jednotlivé ID štruktúr a akonáhle jednotlivé inštancie zistia, že je súbor prázdny, inštancia sa ukončí. Platí, že jedna inštancia obstaráva vždy jednu neklasifikovanú štruktúru so všetkými klasifikovanými.

Chod inštancií, ktoré v skutočnosti prebiehajú v pozadí, môžeme sledovať v termináli a údaje o ohodnotení jednotlivých dvojíc štruktúr sa ukladajú do priečinka \textit{data/}. V tomto priečinku sú ďalšie adresáre pomenované podľa neklasifikovaných štruktúr a v nich sa nachádzajú súbory obsahujúce poradové číslo generácie evolučného procesu a \textit{fitness} (RMSD) získané pri porovnávaní s jednotlivými klasifikovanými štruktúrami. V priečinku \textit{data/} ešte môžeme vidieť súbor \textit{main\_results.txt}, do ktorého sa zaznamenávajú najmenšie hodnoty RMSD jednotlivých porovnávajúcich dvojíc štruktúr, ktorých evolučný proces dobehol úspešne do konca.

V súbore \textit{logs/log.txt} sa nachádzajú všetky výpisy o procesoch jednotlivých porovnávaní ako načítaní jednotlivých súborov, dokončenia priebehu sekvenčného zarovnania, dokončenia prevodu na objekty AP-Tree a zakončenia algoritmov genetického programovania. Rovnako sa tu môžu nachádzať informácie o výnimkách a chybách.

Implementované sú dva základné typy výnimiek. Prvou z nich je výnimka týkajúca sa stavu, kedy program nedokáže nájsť súbor s danou štruktúrou. Pripomíname, že všetky súbory (s koncovkou \textit{.ent}) sa majú nachádzať v spoločnom priečinku na jednej úrovni. Výnimka nesúca informácie o tejto chyba sa volá \textit{CannotReadFileException} a pod týmto názvom sa v chybovom výpise môže vyskytovať.

Druhý typ výnimky sa nazýva \textit{PdbFileParseException}, ktorá sa vyskytne vtedy, ak PDB súbor (v našom prípade s koncovkou \textit{.ent}) obsahuje pre nás dôležité informácie, ktoré sú ale popísané v nesprávnom formáte. Zoznam možných chýb môžeme nájsť v implementácii v triede \textit{PdbFileParseException} v štruktúre \textit{struct FieldMap}.

Po ukončení všetkých inštancií následne spustíme skript \textit{get\_sim.sh}, ktorý prejde priečinok \textit{data/} so zaznamenanými výsledkami a do súboru \textit{similarities.txt} na každý riadok vloží dvojicu štruktúr najviac podobných s príslušnou hodnotou RMSD. Tieto dvojice môžeme následne porovnať s manuálnou klasifikáciou SCOP\footnote{Klasifikáciu určitej bielkoviny môžeme nájsť na internetovej stránke databázy SCOP, konkrétne napr na URL: \url{http://scop.mrc-lmb.cam.ac.uk/scop/data/scop.b.html}.}.

